''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Battery Management Program for Caravan 12V System        '
' Copyright Doug Pankhurst May 2013                        '
' Written for MMBasic V4.3a, copyright Geoff Graham 2012    '
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 File Version:    2.04 May 2013

 This is an updated (Mark II   ;-)  ) version of a program first submitted
 in May 2012.  Lots of comments and it only JUST fits into a CMM running
 in 8 colour mode - I have intentionally made it verbose and not optimised
 to allow easy reading. 

 This program monitors a 12V Battery System, monitoring the battery voltage,
 the solar panel voltage and the amount of charge supplied into and out of the
 battery via current shunt ICs. The charge/discharge state of the battery is 
 given by comparing current in versus current out.

 It also estimates time to 30% capacity based on battery voltage
 and current discharge rate and provides a warning.
 
 Real time data is displayed on VGA display as well as historical
 data recorded to a log file on the SD card for later analysis.

 It utilises a range of subroutines and defined funtions based on software and
 ideas from Doug Pankhurst, Geoff Graham, Tom Pankhurst, and also from programs
 provided in the MMBASIC Software library, authors unknown.
 This code is free for anyone to use or modify as long as they acknowledge
 it's source and credit the contributors above.

 Physical configuration:

 Uses a CG Colourmax 2 as the hardware platform and an Arduino blank shield
 populated with voltage dividers for battery and solar voltages and Allegro ACS758
 current sensors for input (charging) current and load current.  Battery
 charge/discharge current is calculated by subtracting load current from
 charging current.

 The 11.8V to 14.4V from the caravan battery system (depending on whether charging
 or driving load) is fed into an LM317 variable voltage regulator to provide 
 regulated 8.5V to the CGCMM.

 WARNING: The Allegro current sensors have VERY fragile leads so they need to be
 physically stabilised. The units I used were unidirectional and had an offset around
 600mV and a 60mV/amp capacity.

 A general synopsis of the program is as follows:-
 Disable interrupts;
 Define and initialise variables and constants;
 Initialise display with static data; initialize 1 minute arrays to allow averaging
 Enter main loop; wait for interrupt ( which sets NewData flag) then handle 2 second,
 1 minute, 1 hour and end of day (6AM) occurrences.
 Start main loop, waiting for  (set by interrupt routine);
 Cycle through 2 second, 1 minute, 1 hour and End-of-Day processing with initial
 data and display initial readings;
 -   2 second routine processes all instantaneous readings from interrupt routines - 
     battery voltage, solar array voltage, input current from both solar controller
     and/or 240VAC battery charger
 -   1 minute routine averages 30 two second readings, then pushes the averages
     into an array; also writes out running graph
 -   1 hour routine takes array data and writes out to files in .CSV format
 -   EOD ( at 6AM ) closes log file and creates a new log file; 
 Interrupt provides battery volts, solar volts, input current and load current.


Global Variables - these are here just for explanatory purposes - they are defined
in the program proper.  The initialised values are to simplify averaging and also
represent typical values.

BVolts = 12.8      '  Battery Voltage read from Pin A0. Read as 1/6th of
                   ' real voltage via 6:1 resistive divider

Dim BVArray(29)    ' Battery Volts 30 element array - 1 each 2 secs

BatCharge = 100    ' Battery state of charge as a percentage where
                   ' 12.75V or higher is 100%, down to 12.05V, being 35%
                   ' - danger level

AverageBV=12.8     ' Average battery voltage over last 60 seconds

Dim BVAArray(59)   ' 1 hours worth of minute average battery volts

DeltaBV = 0.1      ' Battery voltage variation over 60 seconds. The
                   ' difference between the first and the last used to
                   ' calculate the "Time to 30% discharge point"

Time2Discharge = 20' Time to 30% discharge

SVolts = 20        ' Solar Array voltage from Pin A1. Read as 1/10th
                   ' of real voltage by 10:1 resistive divider

Dim SVArray(29)    ' Solar Volts 30 element array - 1 each 2 secs

AverageSV = 21     ' Average Solar Panel volts over last 60 seconds

Dim SVAArray(59)   ' 1 hours worth of minute average solar volts

InputCurrent = 18  ' Charging current into battery/load read from Pin A2
                   ' 2.5V reading = 50mA across the shunt, which = 50A through shunt.
                   ' This can be both battery charging current and load current.

Dim ICArray(29)    ' Input Current 30 element array

AverageIC = 18     ' Average input (generator) current over last 60 seconds

Dim ICAArray(59)   ' array with 1 hours worth of minute average input currents

LoadCurrent = 12   ' Load current of caravan - can be supplied from the
                   ' batteries and the charging systems (solar, AC Mains or
                   ' generator). Pin A3

Dim LCArray(29)    ' Load Current 60 element array

AverageLC = 12     ' Average load current over last 60 seconds

Dim LCAArray(59)   ' array to hold 1 hours worth of average load currents

BatCurrent = 6     ' A calculated value; if positive, = a charging
                   ' current to the battery; if negative, = a discharge current
                   ' from the battery.

AverageBC = 6      ' Average charge/discharge current over last min
                   ' calculated by AverageLC-AverageIC

InputCurrentAH = 0 ' Input current as an amp hour calculated value -
                   ' this is an accumulating value over 24 hours

PreviousICAH = 0   ' yesterdays Input Current AHs

LoadCurrentAH = 0  ' Load current as an amp hour calculated value -
                   ' this is an accumulating value over 24 hours

PreviousLCAH = 0   ' yesterdays Load Current AHs

BatCurrentAH = 0   ' Bat charge (pos value) or discharge (neg value)
                   ' as an amp hour calculated value  - accumulating
                   ' value over 24 hours

PreviousBCAH = 5   ' yesterdays Bat Current AHs

LogArray$ = ""     ' String to use for plugging into log array

NewDataFlag = 0    ' Two second flag - set every 2 seconds by the
                   ' interrupt routine when new voltage and current
                   ' values are collected.

MinFlag = 0        ' Minute flag - set once every min at 00 seconds
                   ' by sec interrupt process and cleared by min processing code.

HourFlag = 0       ' Hour Flag - set on the hour to enable
                   ' writing the 60 average readings in the log array to be
                   ' writtent to file

EODFlag = 0        ' End of Day Flag - set at 6AM to enable daily log file
                   ' to be closed and new log file created by LogFileCreate subroutine
